.TH OSSFS "1" "December 2015" "OSSFS" "User Commands"
.SH NAME
OSSFS \- FUSE-based file system backed by Aliyun OSS
.SH SYNOPSIS
.SS mounting
.TP
\fBossfs bucket[:/path] mountpoint \fP [options]
.SS unmounting
.TP
\fBumount mountpoint
.SS utility mode ( remove interrupted multipart uploading objects )
.TP
\fBossfs \-u bucket
.SH DESCRIPTION
ossfs is a FUSE filesystem that allows you to mount an Aliyun OSS bucket as a local filesystem. It stores files natively and transparently in OSS (i.e., you can use other programs to access the same files).
.SH AUTHENTICATION
The ossfs password file has this format (use this format if you have only one set of credentials):
.RS 4
\fBaccessKeyId\fP:\fBsecretAccessKey\fP
.RE

If you have more than one set of credentials, this syntax is also recognized:
.RS 4
\fBbucketName\fP:\fBaccessKeyId\fP:\fBsecretAccessKey\fP
.RE
.PP
Password files can be stored in two locations:
.RS 4
 \fB/etc/passwd-ossfs\fP     [0640]
 \fB$HOME/.passwd-ossfs\fP   [0600]
.RE
.SH OPTIONS
.SS "general options"
.TP
\fB\-h\fR   \fB\-\-help\fR
print help
.TP
\fB\  \fR   \fB\-\-version\fR
print version
.TP
\fB\-f\fR
FUSE foreground option - do not run as daemon.
.TP
\fB\-s\fR
FUSE singlethreaded option (disables multi-threaded operation)
.SS "mount options"
.TP
All ossfs options must given in the form where "opt" is:
 <option_name>=<option_value>
.TP
\fB\-o\fR default_acl (default="private")
the default canned acl to apply to all written OSS objects, e.g., "public-read".
Any created files will have this canned acl.
Any updated files will also have this canned acl applied!
.TP
\fB\-o\fR retries (default="2")
number of times to retry a failed OSS transaction.
.TP
\fB\-o\fR use_cache (default="" which means disabled)
local folder to use for local file cache.
.TP
\fB\-o\fR del_cache - delete local file cache
delete local file cache when ossfs starts and exits.
.TP
\fB\-o\fR storage_class (default is standard)
store object with specified storage class.
this option replaces the old option use_rrs.
Possible values: standard, standard_ia, and reduced_redundancy.
.TP
\fB\-o\fR use_rrs (default is disable)
use Aliyun's Reduced Redundancy Storage.
this option can not be specified with use_sse.
(can specify use_rrs=1 for old version)
this option has been replaced by new storage_class option.
.TP
\fB\-o\fR use_sse (default is disable)
Specify two type Aliyun's Server-Site Encryption: SSE-OSS, SSE-C. SSE-OSS uses Aliyun OSS-managed encryption keys, SSE-C uses customer-provided encryption keys.
You can specify "use_sse" or "use_sse=1" enables SSE-OSS type (use_sse=1 is old type parameter).
Case of setting SSE-C, you can specify "use_sse=custom", "use_sse=custom:<custom key file path>" or "use_sse=<custom key file path>"(only <custom key file path> specified is old type parameter).
You can use "c" for short "custom".
The custom key file must be 600 permission. The file can have some lines, each line is one SSE-C key.
The first line in file is used as Customer-Provided Encryption Keys for uploading and changing headers etc.
If there are some keys after first line, those are used downloading object which are encrypted by not first key.
So that, you can keep all SSE-C keys in file, that is SSE-C key history.
If you specify "custom"("c") without file path, you need to set custom key by load_sse_c option or AWSSSECKEYS environment.(AWSSSECKEYS environment has some SSE-C keys with ":" separator.)
This option is used to decide the SSE type.
So that if you do not want to encrypt a object at uploading, but you need to decrypt encrypted object at downloaing, you can use load_sse_c option instead of this option.
For setting SSE-KMS, specify "use_sse=kmsid" or "use_sse=kmsid:<kms id>".
You can use "k" for short "kmsid".
If you san specify SSE-KMS type with your <kms id> in AWS KMS, you can set it after "kmsid:"(or "k:").
If you specify only "kmsid"("k"), you need to set AWSSSEKMSID environment which value is <kms id>.
You must be careful about that you can not use the KMS id which is not same EC2 region.
.TP
\fB\-o\fR load_sse_c - specify SSE-C keys
Specify the custom-provided encription keys file path for decrypting at duwnloading.
If you use the custom-provided encription key at uploading, you specify with "use_sse=custom".
The file has many lines, one line means one custom key.
So that you can keep all SSE-C keys in file, that is SSE-C key history.
AWSSSECKEYS environment is as same as this file contents.
.TP
\fB\-o\fR passwd_file (default="")
specify the path to the password file, which which takes precedence over the password in $HOME/.passwd-ossfs and /etc/passwd-ossfs
.TP
\fB\-o\fR ahbe_conf (default="" which means disabled)
This option specifies the configuration file path which file is the additional HTTP header by file(object) extension.
 The configuration file format is below:
 -----------
 line         = [file suffix] HTTP-header [HTTP-values]
 file suffix  = file(object) suffix, if this field is empty, it means "*"(all object).
 HTTP-header  = additional HTTP header name
 HTTP-values  = additional HTTP header value
 -----------
 Sample:
 -----------
 .gz      Content-Encoding     gzip
 .Z       Content-Encoding     compress
          X-S3FS-MYHTTPHEAD    myvalue
 -----------
 A sample configuration file is uploaded in "test" directory.
If you specify this option for set "Content-Encoding" HTTP header, please take care for RFC 2616.
.TP
\fB\-o\fR public_bucket (default="" which means disabled)
anonymously mount a public bucket when set to 1, ignores the $HOME/.passwd-ossfs and /etc/passwd-ossfs files.
.TP
\fB\-o\fR connect_timeout (default="300" seconds)
time to wait for connection before giving up.
.TP
\fB\-o\fR readwrite_timeout (default="60" seconds)
time to wait between read/write activity before giving up.
.TP
\fB\-o\fR max_stat_cache_size (default="1000" entries (about 4MB))
maximum number of entries in the stat cache
.TP
\fB\-o\fR stat_cache_expire (default is no expire)
specify expire time(seconds) for entries in the stat cache
.TP
\fB\-o\fR enable_noobj_cache (default is disable)
enable cache entries for the object which does not exist.
ossfs always has to check whether file(or sub directory) exists under object(path) when ossfs does some command, since ossfs has recognized a directory which does not exist and has files or sub directories under itself.
It increases ListBucket request and makes performance bad.
You can specify this option for performance, ossfs memorizes in stat cache that the object(file or directory) does not exist.
.TP
\fB\-o\fR no_check_certificate (by default this option is disabled)
do not check ssl certificate.
server certificate won't be checked against the available certificate authorities.
.TP
\fB\-o\fR nodnscache - disable dns cache.
ossfs is always using dns cache, this option make dns cache disable.
.TP
\fB\-o\fR nosscache - disable ssl session cache.
ossfs is always using ssl session cache, this option make ssl session cache disable.
.TP
\fB\-o\fR multireq_max (default="20")
maximum number of parallel request for listing objects.
.TP
\fB\-o\fR parallel_count (default="5")
number of parallel request for uploading big objects.
ossfs uploads large object(default:over 20MB) by multipart post request, and sends parallel requests.
This option limits parallel request count which ossfs requests at once.
It is necessary to set this value depending on a CPU and a network band.
.TP
\fB\-o\fR multipart_size(default="10"(10MB))
number of one part size in multipart uploading request.
The default size is 10MB(10485760byte), minimum value is 5MB(5242880byte).
Specify number of MB and over 5(MB).
.TP
\fB\-o\fR ensure_diskfree(default the same as multipart_size value)
sets MB to ensure disk free space. This option means the threshold of free space size on disk which is used for the cache file by ossfs.
ossfs makes file for downloading, and uploading and caching files.
If the disk free space is smaller than this value, ossfs do not use diskspace as possible in exchange for the performance.
.TP
\fB\-o\fR url (default="http://oss-cn-hangzhou.aliyuncs.com")
sets the url to use to access Aliyun OSS. If you want to use HTTPS, then you can set url=https://oss-cn-hangzhou.aliyuncs.com
.TP
\fB\-o\fR endpoint (default="oss-cn-hangzhou")
sets the endpoint to use.
If this option is not specified, ossfs uses HangZhou region as the default.
If the ossfs could not connect to the region specified by this option, ossfs could not run.
But if you do not specify this option, and if you can not connect with the default region, ossfs will retry to automatically connect to the other region.
So ossfs can know the correct region name, because ossfs can find it in an error from the OSS server.
.TP
\fB\-o\fR mp_umask (default is "0000")
sets umask for the mount point directory.
If allow_other option is not set, ossfs allows access to the mount point only to the owner.
In the opposite case ossfs allows access to all users as the default.
But if you set the allow_other with this option, you can controll the permission permissions of the mount point by this option like umask.
.TP
\fB\-o\fR nomultipart - disable multipart uploads
.TP
\fB\-o\fR enable_content_md5 ( default is disable )
verifying uploaded data without multipart by content-md5 header.
Enable to send "Content-MD5" header when uploading a object without multipart posting.
If this option is enabled, it has some influences on a performance of ossfs when uploading small object.
Because ossfs always checks MD5 when uploading large object, this option does not affect on large object.
.TP
\fB\-o\fR ram_role ( default is no role )
set the RAM Role that will supply the credentials from the instance meta-data.
.TP
\fB\-o\fR noxmlns - disable registing xml name space.
disable registing xml name space for response of ListBucketResult and ListVersionsResult etc. 
This option should not be specified now, because ossfs looks up xmlns automatically after v1.66.
.TP
\fB\-o\fR nocopyapi - for other incomplete compatibility object storage.
For a distributed object storage which is compatibility OSS API without PUT(copy api).
If you set this option, ossfs do not use PUT with "x-oss-copy-source"(copy api). Because traffic is increased 2-3 times by this option, we do not recommend this.
.TP
\fB\-o\fR norenameapi - for other incomplete compatibility object storage.
For a distributed object storage which is compatibility OSS API without PUT(copy api).
This option is a subset of nocopyapi option. The nocopyapi option does not use copy-api for all command(ex. chmod, chown, touch, mv, etc), but this option does not use copy-api for only rename command(ex. mv).
If this option is specified with nocopapi, the ossfs ignores it.
.TP
\fB\-o\fR use_path_request_style (use legacy API calling style)
Enble compatibility with OSS-like APIs which do not support the virtual-host request style, by using the older path request style.
.TP
\fB\-o\fR dbglevel (default="crit")
Set the debug message level. set value as crit(critical), err(error), warn(warning), info(information) to debug level. default debug level is critical.
If ossfs run with "-d" option, the debug level is set information.
When ossfs catch the signal SIGUSR2, the debug level is bumpup.
.TP
\fB\-o\fR curldbg - put curl debug message
Put the debug message from libcurl when this option is specified.
.SH FUSE/MOUNT OPTIONS
.TP
Most of the generic mount options described in 'man mount' are supported (ro, rw, suid, nosuid, dev, nodev, exec, noexec, atime, noatime, sync async, dirsync).  Filesystems are mounted with '\-onodev,nosuid' by default, which can only be overridden by a privileged user.
.TP
There are many FUSE specific mount options that can be specified. e.g. allow_other. See the FUSE README for the full set.
.SH NOTES
.TP
Maximum file size=64GB (limited by ossfs, not Aliyun OSS).
.TP
If enabled via the "use_cache" option, ossfs automatically maintains a local cache of files in the folder specified by use_cache. Whenever ossfs needs to read or write a file on OSS, it first downloads the entire file locally to the folder specified by use_cache and operates on it. When fuse_release() is called, ossfs will re-upload the file to OSS if it has been changed. ossfs uses md5 checksums to minimize downloads from OSS.
.TP
The folder specified by use_cache is just a local cache. It can be deleted at any time. ossfs rebuilds it on demand.
.TP
Local file caching works by calculating and comparing md5 checksums (ETag HTTP header).
.TP
ossfs leverages /etc/mime.types to "guess" the "correct" content-type based on file name extension. This means that you can copy a website to OSS and serve it up directly from OSS with correct content-types!
.SH BUGS
Due to OSS's "eventual consistency" limitations, file creation can and will occasionally fail. Even after a successful create, subsequent reads can fail for an indeterminate time, even after one or more successful reads. Create and read enough files and you will eventually encounter this failure. This is not a flaw in ossfs and it is not something a FUSE wrapper like ossfs can work around. The retries option does not address this issue. Your application must either tolerate or compensate for these failures, for example by retrying creates or reads.
.SH AUTHOR
ossfs is built based on s3fs.
